26 Algorithms library [algorithms]

26.7 Mutating sequence operations [alg.modifying.operations]

26.7.8 Remove [alg.remove]

template<class ForwardIterator, class T = iterator_traits<ForwardIterator>::value_type>
  constexpr ForwardIterator remove(ForwardIterator first, ForwardIterator last,
                                   const T& value);
template<class ExecutionPolicy, class ForwardIterator,
         class T = iterator_traits<ForwardIterator>::value_type>
  ForwardIterator remove(ExecutionPolicy&& exec,
                         ForwardIterator first, ForwardIterator last,
                         const T& value);

template<class ForwardIterator, class Predicate>
  constexpr ForwardIterator remove_if(ForwardIterator first, ForwardIterator last,
                                      Predicate pred);
template<class ExecutionPolicy, class ForwardIterator, class Predicate>
  ForwardIterator remove_if(ExecutionPolicy&& exec,
                            ForwardIterator first, ForwardIterator last,
                            Predicate pred);

template<permutable I, sentinel_for<I> S, class Proj = identity,
         class T = projected_value_t<I, Proj>>
  requires indirect_binary_predicate<ranges::equal_to, projected<I, Proj>, const T*>
  constexpr subrange<I> ranges::remove(I first, S last, const T& value, Proj proj = {});
template<forward_range R, class Proj = identity,
         class T = projected_value_t<iterator_t<R>, Proj>>
  requires permutable<iterator_t<R>> &&
           indirect_binary_predicate<ranges::equal_to, projected<iterator_t<R>, Proj>, const T*>
  constexpr borrowed_subrange_t<R>
    ranges::remove(R&& r, const T& value, Proj proj = {});

template<execution-policy Ep, random_access_iterator I, sized_sentinel_for<I> S,
         class Proj = identity, class T = projected_value_t<I, Proj>>
  requires indirect_binary_predicate<ranges::equal_to, projected<I, Proj>, const T*>
  subrange<I>
    ranges::remove(Ep&& exec, I first, S last, const T& value, Proj proj = {});
template<execution-policy Ep, sized-random-access-range R, class Proj = identity,
         class T = projected_value_t<iterator_t<R>, Proj>>
  requires permutable<iterator_t<R>> &&
           indirect_binary_predicate<ranges::equal_to,
                                      projected<iterator_t<R>, Proj>, const T*>
  borrowed_subrange_t<R>
    ranges::remove(Ep&& exec, R&& r, const T& value, Proj proj = {});

template<permutable I, sentinel_for<I> S, class Proj = identity,
         indirect_unary_predicate<projected<I, Proj>> Pred>
  constexpr subrange<I> ranges::remove_if(I first, S last, Pred pred, Proj proj = {});
template<forward_range R, class Proj = identity,
         indirect_unary_predicate<projected<iterator_t<R>, Proj>> Pred>
  requires permutable<iterator_t<R>>
  constexpr borrowed_subrange_t<R>
    ranges::remove_if(R&& r, Pred pred, Proj proj = {});

template<execution-policy Ep, random_access_iterator I, sized_sentinel_for<I> S,
         class Proj = identity, indirect_unary_predicate<projected<I, Proj>> Pred>
  subrange<I>
    ranges::remove_if(Ep&& exec, I first, S last, Pred pred, Proj proj = {});
template<execution-policy Ep, sized-random-access-range R, class Proj = identity,
         indirect_unary_predicate<projected<iterator_t<R>, Proj>> Pred>
  requires permutable<iterator_t<R>>
  borrowed_subrange_t<R>
    ranges::remove_if(Ep&& exec, R&& r, Pred pred, Proj proj = {});

Let E be

(1.1)
bool(*i == value) for remove;
(1.2)
bool(pred(*i)) for remove_if;
(1.3)
bool(invoke(proj, *i) == value) for ranges::remove;
(1.4)
bool(invoke(pred, invoke(proj, *i))) for ranges::remove_if.

Preconditions: For the algorithms in namespace std, the type of *first meets the Cpp17MoveAssignable requirements (Table 33).

Effects: Eliminates all the elements referred to by iterator i in the range [first, last) for which E holds.

Returns: Let j be the end of the resulting range.

Returns:

(4.1)
j for the overloads in namespace std.
(4.2)
{j, last} for the overloads in namespace ranges.

Complexity: Exactly last - first applications of the corresponding predicate and any projection.

Remarks: Stable ([algorithm.stable]).

[Note 1:

Each element in the range [ret, last), where ret is the returned value, has a valid but unspecified state, because the algorithms can eliminate elements by moving from elements that were originally in that range.

— end note]

🔗

template<class InputIterator, class OutputIterator,
         class T = iterator_traits<InputIterator>::value_type>
  constexpr OutputIterator
    remove_copy(InputIterator first, InputIterator last,
                OutputIterator result, const T& value);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
         class T = iterator_traits<ForwardIterator1>::value_type>
  ForwardIterator2
    remove_copy(ExecutionPolicy&& exec,
                ForwardIterator1 first, ForwardIterator1 last,
                ForwardIterator2 result, const T& value);

template<class InputIterator, class OutputIterator, class Predicate>
  constexpr OutputIterator
    remove_copy_if(InputIterator first, InputIterator last,
                   OutputIterator result, Predicate pred);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
         class Predicate>
  ForwardIterator2
    remove_copy_if(ExecutionPolicy&& exec,
                   ForwardIterator1 first, ForwardIterator1 last,
                   ForwardIterator2 result, Predicate pred);

template<input_iterator I, sentinel_for<I> S, weakly_incrementable O,
         class Proj = identity, class T = projected_value_t<I, Proj>>
  requires indirectly_copyable<I, O> &&
           indirect_binary_predicate<ranges::equal_to, projected<I, Proj>, const T*>
  constexpr ranges::remove_copy_result<I, O>
    ranges::remove_copy(I first, S last, O result, const T& value, Proj proj = {});
template<input_range R, weakly_incrementable O, class Proj = identity,
         class T = projected_value_t<iterator_t<R>, Proj>>
  requires indirectly_copyable<iterator_t<R>, O> &&
           indirect_binary_predicate<ranges::equal_to, projected<iterator_t<R>, Proj>, const T*>
  constexpr ranges::remove_copy_result<borrowed_iterator_t<R>, O>
    ranges::remove_copy(R&& r, O result, const T& value, Proj proj = {});

template<execution-policy Ep, random_access_iterator I, sized_sentinel_for<I> S,
         random_access_iterator O, sized_sentinel_for<O> OutS,
         class Proj = identity, class T = projected_value_t<I, Proj>>
  requires indirectly_copyable<I, O> &&
           indirect_binary_predicate<ranges::equal_to, projected<I, Proj>, const T*>
  ranges::remove_copy_result<I, O>
    ranges::remove_copy(Ep&& exec, I first, S last, O result, OutS result_last,
                        const T& value, Proj proj = {});
template<execution-policy Ep, sized-random-access-range R, sized-random-access-range OutR,
         class Proj = identity, class T = projected_value_t<iterator_t<R>, Proj>>
  requires indirectly_copyable<iterator_t<R>, iterator_t<OutR>> &&
           indirect_binary_predicate<ranges::equal_to,
                                      projected<iterator_t<R>, Proj>, const T*>
  ranges::remove_copy_result<borrowed_iterator_t<R>, borrowed_iterator_t<OutR>>
    ranges::remove_copy(Ep&& exec, R&& r, OutR&& result_r, const T& value, Proj proj = {});

template<input_iterator I, sentinel_for<I> S, weakly_incrementable O,
         class Proj = identity, indirect_unary_predicate<projected<I, Proj>> Pred>
  requires indirectly_copyable<I, O>
  constexpr ranges::remove_copy_if_result<I, O>
    ranges::remove_copy_if(I first, S last, O result, Pred pred, Proj proj = {});
template<input_range R, weakly_incrementable O, class Proj = identity,
         indirect_unary_predicate<projected<iterator_t<R>, Proj>> Pred>
  requires indirectly_copyable<iterator_t<R>, O>
  constexpr ranges::remove_copy_if_result<borrowed_iterator_t<R>, O>
    ranges::remove_copy_if(R&& r, O result, Pred pred, Proj proj = {});

template<execution-policy Ep, random_access_iterator I, sized_sentinel_for<I> S,
         random_access_iterator O, sized_sentinel_for<O> OutS,
         class Proj = identity, indirect_unary_predicate<projected<I, Proj>> Pred>
  requires indirectly_copyable<I, O>
  ranges::remove_copy_if_result<I, O>
    ranges::remove_copy_if(Ep&& exec, I first, S last, O result, OutS result_last,
                           Pred pred, Proj proj = {});
template<execution-policy Ep, sized-random-access-range R, sized-random-access-range OutR,
         class Proj = identity,
         indirect_unary_predicate<projected<iterator_t<R>, Proj>> Pred>
  requires indirectly_copyable<iterator_t<R>, iterator_t<OutR>>
  ranges::remove_copy_if_result<borrowed_iterator_t<R>, borrowed_iterator_t<OutR>>
    ranges::remove_copy_if(Ep&& exec, R&& r, OutR&& result_r, Pred pred, Proj proj = {});

Let E(i) be

(8.1)
bool(*i == value) for remove_copy;
(8.2)
bool(pred(*i)) for remove_copy_if;
(8.3)
bool(invoke(proj, *i) == value) for ranges::remove_copy;
(8.4)
bool(invoke(pred, invoke(proj, *i))) for ranges::remove_copy_if.

Let:

(9.1)
M be the number of iterators i in [first, last) for which E(i) is false;
(9.2)
result_last be result + M for the overloads with no parameter result_last or result_r;
(9.3)
N be min(M, result_last - result).

Mandates: *first is writable ([iterator.requirements.general]) to result.

Preconditions: The ranges [first, last) and [result, result + N) do not overlap.

[Note 2:

For the parallel algorithm overloads in namespace std, there can be a performance cost if iterator_traits<ForwardIterator1>::value_type does not meet the Cpp17MoveConstructible (Table 31) requirements.

For the parallel algorithm overloads in namespace ranges, there can be a performance cost if iter_value_t<I> does not model move_constructible .

— end note]

Effects: Copies the first N elements referred to by the iterator i in the range [first, last) for which E(i) is false into the range [result, result + N).

Returns:

(13.1)
result + N, for the algorithms in namespace std.
(13.2)
{last, result + N}, for the algorithms in namespace ranges, if N is equal to M.
(13.3)
Otherwise, {j, result_last}, for the algorithms in namespace ranges, where j is the iterator in [first, last) for which E(j) is false and there are exactly N iterators i in [first, j) for which E(i) is false.

Complexity: At most last - first applications of the corresponding predicate and any projection.

Remarks: Stable ([algorithm.stable]).